Collections and Automation

Automation defines the IEnumVARIANT interface to provide a standard way for the API clients to iterate over collections. Every collection interface in the API exposes a read-only property named _NewEnum to let the API clients know that the collection supports iteration. The _NewEnum property returns a pointer on the IEnumVARIANT interface.

The IEnumVARIANT interface provides a way to iterate through the items contained by a collection. This interface is supported by an enumerator interface that is returned by the _NewEnum property of the collection.

The IEnumVARIANT interface defines the following member functions:

Next

Retrieves one or more elements in a collection starting with the current element.

Skip

Skips over one or more elements in a collection.

Reset

Resets the current element to the first element in the collection.

Clone

Copies the current state of the enumeration so you can return to the current element after using Skip or Reset.

The IEnumVARIANT collection implements a Rogue Wave Software, Inc. style advance and return iteration. For this reason, they have the following life cycle:

When the iterator is created, it enters the Created state, and then forces itself into the BeforeStart state. A successful advance drives the iterator into the InList state, while an unsuccessful advance drives it into the AtEnd state. A Reset drives the iterator back to the BeforeStart state, and deletion drives it into the Deleted state.

The iterator is positioned over a member of the collection (that is, associated with a current member) only if it is in the InList state.